Swagger ではない OpenAPI Specification 3.0 による API サーバー開発
shimizukawa.iconOpenAPI周りの事情が把握できるとてもよくまとまった資料でした。
2019年11月時点の話なので最新はまた違うかも。
プレゼン資料
JJUG CCC 2019 Fall の発表資料
要約
実装サイクル
生成されたコードをリポジトリで管理しない
Specを書き、APIを実装し、テストを書く
Specファイルの分割と結合
Referenceで参照、外部ファイルも参照できる
ツールによっては1ファイルしか扱えない
結合ツールを作った
コード生成
Javaの話は割愛（斜め読み）
テンプレートのカスタマイズはメンテを考えると控えるべきだが、必要ならやる
良かったこと
ドキュメント自動生成はチーム間連携で好評
テストやCI/CDと相性が良い
モックサーバー構築、テストクライアント生成、多言語対応
慣れればSpecはコピペで書ける
悪かったこと
「ちょっと開発を手伝って」、は不可
APIインターフェースの制約が設計に与える影響が大きい
使用するフレームワークやパラダイムに妥協が強いられる
https://scrapbox.io/files/5f4b5e52ed0eac002313b03a.png
どんなコードが生成されるか
生成されたコードをどう扱うか
どう拡張するか
フレームワークとの連携
パッケージング
カスタマイズとのバランス
CI/CDにどう組み込むか
開発方法論、開発プロセスへの組み込み
外部とのインテグレーションの保証
タグ